home *** CD-ROM | disk | FTP | other *** search
/ The Arsenal Files 8 / The Arsenal Files Collection #8 (Arsenal Computer) (1996).ISO / dosutils / chang611.zip / CHANGE.DOC < prev    next >
Text File  |  1996-11-30  |  18KB  |  401 lines
  1. CHANGE.DOC                           1                         Revised: 11-30-96
  2.  
  3. The CHANGE.EXE program allows you to make changes in binary or text files of any
  4. size.  Features:
  5.  
  6.   * Can handle files of any size provided you have enough room on your disk
  7.     to hold a copy of resulting file.
  8.   * Can be used to change text files or binary files.
  9.   * Can be used to remove trailing spaces from a file.
  10.   * Can specify different lengths for the input strings and the output strings.
  11.   * Can specify that the changes only be done in lines that include a certain
  12.     character string.  This selection string can be case-insensitive.
  13.   * Can handle up to 30 change requests at a time.
  14.   * Can specify the input/output strings as ASCII characters, hexadecimal
  15.     values, or as decimal values.
  16.   * Handles the changes fairly quickly.
  17.   * Can either replace the original file with the resulting file or else
  18.     create a new changed file (using /Noutfile specification).
  19.   * Changes can be interactively verified before they are made.
  20.   * Changes can be entered in any of the following ways:
  21.       - from the command line (one TO/FROM pair allowed)
  22.       - interactively (one TO/FROM pair allowed)
  23.       - from a controlfile (up to 30 TO/FROM pairs allowed)
  24.   * Boolean operators can be used if the TO/FROM pair is specified from the
  25.     command line; for example:
  26.       CHANGE TEST.TXT /FROM One /TO Many /IN Apples OR Oranges
  27.   * The input file specification can include standard DOS wildcards or an
  28.     external file (@listfile) containing the files to be processed (although
  29.     either prohibits using the /Noutfile feature).
  30.   * The input change specification can end with "*" in which case all
  31.     subsequent characters are changed to the end of the line.  For example:
  32.       CHANGE TEST.TXT /FROM DEVICE=C:\BIN\AD* /TO DEVICE=C:\BINNEW\ADNEW.COM
  33.   * The input change specification can include a column specification so only
  34.     characters that fall within a given range of columns are changed.
  35.   * Can be used to eliminate lines that you don't want.  For example:
  36.       CHANGE TEST.TXT /FROM DEVICE=C:\DOS\SMARTDRV.EXE /TO NULL /ZAPNULL
  37.  
  38.  
  39. Specifying parameters:
  40.  
  41. Parameters for this program can be set in the following ways.  The last  setting
  42. encountered always wins:
  43.   - Read from an *.INI file (see BRUCEINI.DOC file),
  44.   - Through the use of an environmental variable (SET CHANGE=whatever), or
  45.   - From the command line (see "Syntax" below)
  46.  
  47.  
  48.  
  49. CHANGE.DOC                           2                         Revised: 11-30-96
  50.  
  51. To/From/In Specifications:
  52.  
  53. The CHANGE program allows you to specify three parts to a change request:
  54.  
  55.   * The text to be replaced
  56.   * The text to replace it with
  57.   * Optionally, a string which the line must contain before the change is made
  58.  
  59. For example, in the following two lines:
  60.  
  61.         The quick brown fox jumped over
  62.         the lazy brown dog.
  63.  
  64. the program allows you to replace the string "brown" with the string "red"  only
  65. in lines that contain the string "fox" (so "brown fox" becomes "red fox").  This
  66. would change the "brown" in the first line but not the one in the second line.
  67.  
  68. In order to enter your change request(s), you can use one of three methods:
  69.  
  70.   * Enter it from the command line using /FROM string, /TO string, /IN string
  71.   * Let the program prompt you for the /FROM and /TO specification (in which
  72.     case no /IN string can be provided)
  73.   * Use a control file
  74.  
  75. The control file is a regular ASCII text file (created with any text editor). It
  76. can contain up to 30 change requests (the other two approaches  only  allow  for
  77. one).  Each line of the control file should consist of records of  one  of  four
  78. record types:
  79.  
  80.   * blank lines or those beginning with semi-colons, colons, or single quotes
  81.     are treated as comments.
  82.   * lines beginning with "-F" or "-f" provide FROM options.
  83.   * lines beginning with "-T" or "-t" provide TO options.
  84.   * lines beginning with "-I" or "-i" provide IN options.  These are optional;
  85.     if not provided, all lines will be searched for the FROM string.  Any
  86.     IN request forces /TEXT mode to be invoked
  87.  
  88. If more than one set of FROM/TO/IN records is  provided,  the  -F  specification
  89. must  precede  the  others.   Each  option  is  local  to  a  given   FROM/TO/IN
  90. specification.  For example:
  91.  
  92.         ; Sample control file
  93.         -FPRINT
  94.         -TPrinting
  95.         -I"
  96.         -fUSING
  97.         -tused
  98.  
  99. contains two FROM/TO/IN specifications.  "PRINT" will be changed  to  "Printing"
  100. in any line with a double quote.  "USING" will  be  changed  to  "used"  in  all
  101. lines; no -I option is applied for the second FROM/TO/IN specification.
  102.  
  103.  
  104. CHANGE.DOC                           3                         Revised: 11-30-96
  105.  
  106. If you want to specify your from/to request from the command  line  and  any  of
  107. your strings contains one or more spaces, enclose the string in double quotation
  108. marks.  For example:
  109.  
  110.         CHANGE BUGBUNNY.TXT /FROM "Elmer Fudd" /TO "Daffy Duck"
  111.  
  112. The FROM/TO/IN specifications can include any text characters.   They  can  also
  113. contain ASCII codes, created either using the Alt key in  combination  with  the
  114. numeric keypad (e.g.  Alt-228 to get a Sigma character) or else by  embedding  a
  115. hexadecimal code (in the form &Hxx) or a decimal code (in the form \nnn) in  the
  116. text.  These codes are described in the  BRUCEHEX.DOC  file.   For  example,  to
  117. change a double carriage return/line feed to a single carriage return/line feed,
  118. you could say:
  119.  
  120.         -F&H0D0A0D0A
  121.         -T&H0D0A
  122.  
  123. (Note that the above example would require you to use  the  /BINARY  option--the
  124. default-- since the lines encountered will extend beyond line boundaries.)
  125.  
  126. If you need to follow a hexadecimal specification with normal  text  characters,
  127. follow the hex spec with one space (which CHANGE will ignore).  For example,
  128.  
  129.         -F&H0c Hi!
  130.         -T&H0d0a Bye!
  131.  
  132. DOS considers certain characters ("|" and ">") to be pipe  characters  and  will
  133. strip them away from the command line before CHANGE gets them.  If you  need  to
  134. specify a change that includes these characters and you want to use the  command
  135. line for it, use the  hexadecimal  or  decimal  codes  instead.   Alternatively,
  136. putting them in quotes seems to usually work.
  137.  
  138. If the "/FROM string" specification ends with an asterisk (e.g. "/FROM BRUCE*"),
  139. the program will look for any instance of the string  before  the  asterisk  and
  140. replace that  string  and  all  subsequent  characters  in  the  line  with  the
  141. designated "/TO string".  Asterisks embedded within the string  (as  opposed  to
  142. being the trailing character of the string) will be read as regular  characters.
  143. If you actually want to replace an asterisk as a  trailing  character,  use  the
  144. &Hxx or \nnn conventions.  Specifying a wildcard like this puts you  into  /TEXT
  145. mode automatically.  Wildcards cannot be used in the "/TO string" specification.
  146.  
  147. The "/FROM string" parameter can include a column  indicator  after  the  string
  148. (and the asterisk if used).  A single column can be specified in which case  the
  149. string to be changed has to be found in that specific column:
  150.  
  151.         CHANGE TEMP.X /FROM ";" 1 /TO NULL /NTEMP.X2
  152.  
  153. Alternatively, the column specification can include a  range  of  columns.   The
  154. "from" specification has to start within that range (although it can end outside
  155. of that range).  For example:
  156.  
  157.         CHANGE TEMP.X /FROM "\" 3/50 /TO "/" /NTEMP.X2
  158.  
  159.  
  160. CHANGE.DOC                           4                         Revised: 11-30-96
  161.  
  162. To remove a string entirely, use  the  -T  without  anything  after  it  or  use
  163. "-TNULL" or "/TO NULL" from the command line.   If  the  /ZAPNULL  parameter  is
  164. provided, if the entire line is reset to nothing, the line will not  be  written
  165. out at all.  This allows you to drop lines if necessary.
  166.  
  167. As far as case-sensitivity is concerned, the /FROM and  /IN  specifications  are
  168. case-sensitive unless /I  is  specified.   The  /TO  specification  is  *always*
  169. case-sensitive.
  170.  
  171.  
  172. Syntax:
  173.  
  174.     CHANGE { filespec | @listfile }
  175.       [ /Cctlfile | /FROM string /TO string [ /IN search ] ]
  176.       [ /LINES { line1-line2 | line1 linect } ... ] [ /V ] [ /I ]
  177.       [ /Noutfile [ /OVERWRITE | /-OVERWRITE | /OVERASK ] ] [ /W | /W0 | /-W ]
  178.       [ /Iinitfile ] [ /Frptfile ] [ /Ttempfile ] [ /TRIM ] [ /ZAPNULL ]
  179.       [ /BINARY | /TEXT ] [ /VERIFY ] [ /MONO ] [ /Q ] [ /? ] [ /?&H ]
  180.  
  181. where:
  182.  
  183. "filespec" tells the routine which file or files are to be  processed.   It  can
  184. include path information if desired.  It can also include standard DOS wildcards
  185. as long as the /Noutfile parameter is not specified.  If a  /Noutfile  parameter
  186. is not provided, the input files are overwritten by the results of this program.
  187. If you'd like to process a lot of files and still create new files, use the  DOS
  188. FOR command instead.  Try something like this:
  189.  
  190.         FOR %A IN (*.TXT) DO CHANGE %A /FROM "A" /TO "B" /N\TEMP\%A
  191.  
  192. "@listfile" allows you to have a variety of file specifications saved in a  text
  193. file named "listfile".  Each line  in  the  file  should  consist  of  one  file
  194. specification, each of which can include a path and wildcards if desired.  Blank
  195. lines and lines beginning with semi-colons, colons, or quotes are ignored.
  196.  
  197. "/Cctlfile" specifies a control file with  the  change  commands  to  make.  See
  198. "To/From/In Specifications" above.
  199.  
  200. "/FROM string /TO string [ /IN search ]"  allows  you  to  specify  the  from/to
  201. parameters on the control line.  See "To/From/In Specifications" above.
  202.  
  203. "/Iinitfile" says to read an initialization file with the file name  "initfile".
  204. The file specification *must* contain a period.  Initfiles are described in  the
  205. BRUCEINI.DOC file.  Initially defaults to "/ICHANGE.INI".
  206.  
  207. "/LINES line1-line2" says to restrict the search to lines between  line  numbers
  208. line1 and line2 inclusive.  You can have multiple line  requests  in  any  order
  209. such as "/LINES 1-10 90-100 30-50".  The  routine  skips  all  lines  after  the
  210. largest line number is encountered.  Defaults to "/LINES 1-9999999".
  211.  
  212. "/LINES line1 linect" says to restrict the search to lines beginning with  line1
  213. and continuing for a total of linect lines.  So "/LINES 10 20" is  actually  the
  214. same as "/LINES 10-29".
  215.  
  216.  
  217. CHANGE.DOC                           5                         Revised: 11-30-96
  218.  
  219. "/V" says to find those items that do NOT match the specification.
  220.  
  221. "/-V" is the opposite of /V and is typically the default.
  222.  
  223. "/I" says to make it a case-insensitive search.
  224.  
  225. "/-I" is the opposite of /I and is typically the default.
  226.  
  227. "/Noutfile" is the name of the new file  to  create.   If  a  /Noutfile  is  not
  228. specified, the source document (infile) will be replaced by the changed file.
  229.  
  230. "/OVERWRITE" says to write over the outfile (if requested) if it exists already.
  231.  
  232. "/-OVERWRITE" says to abort if the outfile exists already.
  233.  
  234. "/OVERASK" says to ask if the outfile exists already.  This is the default.
  235.  
  236. "/W" says to pause with a "Press any key to continue" message after the  program
  237. finishes if any hits were  found.   Note  that  this  parameter  is  ignored  if
  238. redirection out is being used.
  239.  
  240. "/W0" says to pause afterward whether any hits were found  or  not.   Note  that
  241. this parameter is ignored if redirection out is being used.  This  is  initially
  242. the default if the program is run under Windows.
  243.  
  244. "/-W" says to not pause afterward at all.  This is initially the default if  the
  245. program is run under DOS.
  246.  
  247. "/Frptfile" is the name of a file to contain all changed lines.  This allows you
  248. to see what the lines were changed to for verification  purposes.   This  option
  249. automatically invokes /TEXT.  The report file is always appended to so new lines
  250. are written at the end of any existing report file.
  251.  
  252. "/Ttempfile" is the name of the temporary file to create.   The  actual  changes
  253. are written to a temp file and then the source file is replaced  with  the  temp
  254. file is everything works and there were actually changes  to  be  found  in  the
  255. source document.  By default, the temp file is called  {CHANGE}.TMP  and  it  is
  256. written to the same path as the input file.  The temporary file will be  as  big
  257. as the final file is.  If you don't have enough room for it to be on your source
  258. disk,  specify  another  temporary  file  name  with  a  different  path   (e.g.
  259. "/TG:\TEMP.TXT").
  260.  
  261. "/TRIM" says to remove trailing spaces from the end of each line.  Automatically
  262. forces you into TEXT mode.
  263.  
  264. "/-TRIM" is the opposite of /TRIM and is the default.
  265.  
  266. "/ZAPNULL" says that if the output line is changed and ends up empty,  then  the
  267. line should be dropped entirely from the output file.  Requires  you  to  be  in
  268. TEXT mode.
  269.  
  270. "/-ZAPNULL" retains all lines.  This is initially the default.
  271.  
  272.  
  273. CHANGE.DOC                           6                         Revised: 11-30-96
  274.  
  275. "/TEXT" puts you into TEXT mode.  TEXT mode means that all data in the file  are
  276. read in and processed as separate text records.  Alternatively, the file can  be
  277. processed in BINARY mode in which case  the  file  is  read  in  in  12,000-byte
  278. blocks. BINARY mode is quicker and is required for EXE and COM files.  TEXT mode
  279. presents some information  like  the  number  of  lines  in  your  file  and  is
  280. *required* if you specify any of the following options:
  281.  
  282.         * an IN (or -I) request
  283.         * /LINES
  284.         * /Frptfile
  285.         * /TRIM
  286.         * /VERIFY
  287.  
  288. "/BINARY" is the opposite of TEXT mode.   It's  faster  than  TEXT  and  is  the
  289. default for CHANGE.  It is overridden if  you  specify  certain  options  listed
  290. above.
  291.  
  292. "/VERIFY" says to prompt you before  changing  any  lines.   You  are  asked  to
  293. confirm that you in fact want to  make  each  change  requested.   Automatically
  294. forces you into TEXT mode.
  295.  
  296. "/-VERIFY" is the opposite of /VERIFY and is the default.
  297.  
  298. "/MONO" (or "/-COLOR") does  not  try  to  override  screen  colors.   Initially
  299. defaults to "/COLOR".
  300.  
  301. "/COLOR" (or "/-MONO") allows screen colors to be overridden.  This is initially
  302. the default.
  303.  
  304. "/Q" turns off the line-by-line status messages.
  305.  
  306. "/?" or "/HELP" or "HELP" shows you the syntax for the command.
  307.  
  308. "/?&H" gives you a hexadecimal and decimal conversion table.
  309.  
  310.  
  311.  
  312. CHANGE.DOC                           7                         Revised: 11-30-96
  313.  
  314. For search, the syntax is:
  315.  
  316.   [ ( ]... search_item [ boolean [ ( ]... search_item [ ) ]...] [ ) ]...
  317.  
  318. where:
  319.  
  320.   ( and )     are used to group items
  321.   search_item is shown below
  322.   boolean     is AND, OR, or XOR (NOT is included with search_item)
  323.  
  324. for search_item, the syntax is:
  325.  
  326.   [ NOT ]  "string" [ column ]
  327.  
  328. where:
  329.   NOT         is obvious
  330.   string      the string to search; the quotation marks are typically not
  331.               required unless the string contains a space or a reserved word
  332.   column      is the column in which the string must be found.
  333.  
  334. So, let's cover some examples:
  335.  
  336.         CHANGE TEST.TXT /FROM Apple /TO Banana /IN "Bugs Bunny" OR "Elmer Fudd"
  337.  
  338. Changes the string "Apple" to "Banana" in any lines that have  either  the  text
  339. "Bugs Bunny" or "Elmer Fudd" in them.
  340.  
  341.         CHANGE TEST2.TXT /FROM Bugs /TO Bunny /IN (Apples or Oranges) AND NOT
  342.            Pears /LINES 1-1000
  343.  
  344. Changes "Bugs" to "Bunny" in the first thousand lines of  TEST2.TXT.   The  line
  345. itself must contain the words "Apples" or "Oranges" in them and  any  lines  are
  346. ignored that contain "Pears".  Note that the quotes around the search words  are
  347. not required unless the words include spaces or unless they  could  be  confused
  348. with some other keywords.  "CHANGE TEST3.TXT /FROM Bugs /TO Bunny /IN OR OR AND"
  349. might cause the program to get confused since "OR" and "AND", which you want  to
  350. look for as also keywords.
  351.  
  352.         CHANGE /I TEST.TXT /FROM One /TO Many /IN "Bugs Bunny" AND Martians
  353.  
  354. This changes "One" to "Many" is any lines that contain  both  "Bugs  Bunny"  and
  355. "Martians".  The search is case-insensitive so lines with  either  "BUGS  BUNNY"
  356. and "Bugs Bunny" will be changed.
  357.  
  358. NOTE:  THIS EXTENDED SEARCHING CAPABILITY IS SUPPORTED  ONLY  FOR  /IN  REQUESTS
  359. MADE FROM THE COMMAND LINE.  IT IS NOT SUPPORTED IN EITHER THE CTLFILE OR IN THE
  360. INTERACTIVE TO/FROM SELECTION MODE.
  361.  
  362.  
  363. CHANGE.DOC                           8                         Revised: 11-30-96
  364.  
  365. Return codes:
  366.  
  367. CHANGE returns the following ERRORLEVEL codes:
  368.  
  369.         0 = no problems, changes made
  370.         1 = no problems, nothing found to change
  371.       253 = routine aborted early
  372.       254 = internal problems
  373.       255 = syntax problems, file not found, or /? requested
  374.  
  375.  
  376. Author:
  377.  
  378.                         Bruce Guthrie
  379.                         Room H-4885
  380.                         U.S. Dept of Commerce/ESA/STAT-USA
  381.                         Washington, DC 20230
  382.  
  383.                         voice: (202) 482-3234
  384.                         e-mail: bguthrie@doc.gov
  385.  
  386. You may freely copy and re-distribute this program; however, the U.S. Department
  387. of Commerce neither guarantees nor assures compatibility of the program with all
  388. computer software or hardware.
  389.  
  390. Additional information about this and other Bruce Guthrie programs can be  found
  391. in the file BRUCE.DOC which should be included in the original  ZIP  file.   The
  392. recent change history for this  and  the  other  programs  is  provided  in  the
  393. HISTORY.ymm file which should be in the same ZIP file where "y" is  replaced  by
  394. the last digit of the year and "mm" is the  two  digit  month  of  the  release;
  395. HISTORY.611 came out in November 1996.  This same naming convention is  used  in
  396. naming the ZIP file (CHANGymm.ZIP) that this program was included in.
  397.  
  398. Please provide an Internet e-mail address on all correspondence.
  399.  
  400. 
  401.